IMHO the change still doesn't tell the difference between componentUpdated and update. Nevertheless, the whole idea may be better explained with a note instead of an inline, as it involves two hooks instead of only componentUpdated itself. I'd rewrite what Evan said in the channel into something like this:

Though pretty much similar, update and componentUpdated has a subtle difference: When update is called on an element, there’s no guarantee whether its children have also been updated. On the other hand, when componentUpdated is called, the children would have been updated as well. Hence, if your directive relies on its children being already updated, use componentUpdated instead of update.

It's a bit wordy, though. Maybe you guys can shorten it somehow.

@posva @phanan I just made some tweaks to try to simplify the language. What do you think?

it's better. I'll still add the tip that @phanan said

@posva Do you think the tip is still necessary with the bolding? I tried to capture the content of the tip there.

@chrisvfritz No, sorry, it's fine like that. If people find it unclear we can add the tip later on

Sounds good. 🙂 Thanks for making this happen!